16.5 Customizing Embedded Mode

You can modify Embedded mode’s behavior by setting various Lisp variables described here. These variables are customizable (see Customizing Calc), or you can use M-x set-variable or M-x edit-options to adjust a variable on the fly. (Another possibility would be to use a file-local variable annotation at the end of the file; see Local Variables in Files in the Emacs manual.) Many of the variables given mentioned here can be set to depend on the major mode of the editing buffer (see Customizing Calc).

The calc-embedded-open-formula variable holds a regular expression for the opening delimiter of a formula. See Regular Expression Search in the Emacs manual, to see how regular expressions work. Basically, a regular expression is a pattern that Calc can search for. A regular expression that considers blank lines, ‘$’, and ‘$$’ to be opening delimiters is "\\`\\|^\n\\|\\$\\$?". Just in case the meaning of this regular expression is not completely plain, let’s go through it in detail.

The surrounding ‘" "’ marks quote the text between them as a Lisp string. If you left them off, set-variable or edit-options would try to read the regular expression as a Lisp program.

The most obvious property of this regular expression is that it contains indecently many backslashes. There are actually two levels of backslash usage going on here. First, when Lisp reads a quoted string, all pairs of characters beginning with a backslash are interpreted as special characters. Here, \n changes to a new-line character, and \\ changes to a single backslash. So the actual regular expression seen by Calc is ‘\`\|^ (newline) \|\$\$?’.

Regular expressions also consider pairs beginning with backslash to have special meanings. Sometimes the backslash is used to quote a character that otherwise would have a special meaning in a regular expression, like ‘$’, which normally means “end-of-line,” or ‘?’, which means that the preceding item is optional. So ‘\$\$?’ matches either one or two dollar signs.

The other codes in this regular expression are ‘^’, which matches “beginning-of-line,” ‘\|’, which means “or,” and ‘\`’, which matches “beginning-of-buffer.” So the whole pattern means that a formula begins at the beginning of the buffer, or on a newline that occurs at the beginning of a line (i.e., a blank line), or at one or two dollar signs.

The default value of calc-embedded-open-formula looks just like this example, with several more alternatives added on to recognize various other common kinds of delimiters.

By the way, the reason to use ‘^\n’ rather than ‘^$’ or ‘\n\n’, which also would appear to match blank lines, is that the former expression actually “consumes” only one newline character as part of the delimiter, whereas the latter expressions consume zero or two newlines, respectively. The former choice gives the most natural behavior when Calc must operate on a whole formula including its delimiters.

See the Emacs manual for complete details on regular expressions. But just for your convenience, here is a list of all characters which must be quoted with backslash (like ‘\$’) to avoid some special interpretation: ‘. * + ? [ ] ^ $ \’. (Note the backslash in this list; for example, to match ‘\[’ you must use "\\\\\\[". An exercise for the reader is to account for each of these six backslashes!)

The calc-embedded-close-formula variable holds a regular expression for the closing delimiter of a formula. A closing regular expression to match the above example would be "\\'\\|\n$\\|\\$\\$?". This is almost the same as the other one, except it now uses ‘\'’ (“end-of-buffer”) and ‘\n$’ (newline occurring at end of line, yet another way of describing a blank line that is more appropriate for this case).

The calc-embedded-word-regexp variable holds a regular expression used to define an expression to look for (a “word”) when you type C-x * w to enable Embedded mode.

The calc-embedded-open-plain variable is a string which begins a “plain” formula written in front of the formatted formula when d p mode is turned on. Note that this is an actual string, not a regular expression, because Calc must be able to write this string into a buffer as well as to recognize it. The default string is "%%% " (note the trailing space), but may be different for certain major modes.

The calc-embedded-close-plain variable is a string which ends a “plain” formula. The default is " %%%\n", but may be different for different major modes. Without the trailing newline here, the first line of a Big mode formula that followed might be shifted over with respect to the other lines.

The calc-embedded-open-new-formula variable is a string which is inserted at the front of a new formula when you type C-x * f. Its default value is "\n\n". If this string begins with a newline character and the C-x * f is typed at the beginning of a line, C-x * f will skip this first newline to avoid introducing unnecessary blank lines in the file.

The calc-embedded-close-new-formula variable is the corresponding string which is inserted at the end of a new formula. Its default value is also "\n\n". The final newline is omitted by C-x * f if typed at the end of a line. (It follows that if C-x * f is typed on a blank line, both a leading opening newline and a trailing closing newline are omitted.)

The calc-embedded-announce-formula variable is a regular expression which is sure to be followed by an embedded formula. The C-x * a command searches for this pattern as well as for ‘=>’ and ‘:=’ operators. Note that C-x * a will not activate just anything surrounded by formula delimiters; after all, blank lines are considered formula delimiters by default! But if your language includes a delimiter which can only occur actually in front of a formula, you can take advantage of it here. The default pattern is "%Embed\n\\(% .*\n\\)*", but may be different for different major modes. This pattern will check for ‘%Embed’ followed by any number of lines beginning with ‘%’ and a space. This last is important to make Calc consider mode annotations part of the pattern, so that the formula’s opening delimiter really is sure to follow the pattern.

The calc-embedded-open-mode variable is a string (not a regular expression) which should precede a mode annotation. Calc never scans for this string; Calc always looks for the annotation itself. But this is the string that is inserted before the opening bracket when Calc adds an annotation on its own. The default is "% ", but may be different for different major modes.

The calc-embedded-close-mode variable is a string which follows a mode annotation written by Calc. Its default value is simply a newline, "\n", but may be different for different major modes. If you change this, it is a good idea still to end with a newline so that mode annotations will appear on lines by themselves.